Enforce repo checkpoint policy#1509
Merged
Merged
Conversation
Read the repo checkpoint policy before committed checkpoint writes and skip unsupported hook writes without failing ordinary git operations. Refresh policy during pre-push, warn user-driven commands when the local policy requires a newer CLI, and document the offline/online behavior. Entire-Checkpoint: 8712032f8b90
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull request overview
Wires the repository’s stored checkpoint policy (refs/entire/policies/checkpoint) into runtime behavior, gating committed checkpoint writes and checkpoint pushes so older CLIs don’t emit incompatible metadata while keeping hook-triggered git workflows non-fatal.
Changes:
- Enforce local checkpoint policy on user-driven committed checkpoint writes (fail with an upgrade instruction when policy requires an unsupported writer).
- Make hook-triggered checkpoint writes and pre-push checkpoint pushes skip (and warn/log) when policy is unsupported; pre-push refreshes policy before deciding to push metadata.
- Add post-success warning printing when local policy indicates the CLI should be upgraded, plus supporting policy helper APIs and tests.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/architecture/sessions-and-checkpoints.md | Documents the checkpoint policy ref, fields, and enforcement behavior across hooks/user commands/pre-push. |
| cmd/entire/main.go | Prints checkpoint-policy upgrade warning after successful command execution (for non-excluded commands). |
| cmd/entire/cli/versioncheck/versioncheck.go | Adds UpdateCommandForCurrentBinary helper to pick either an installer command or releases URL. |
| cmd/entire/cli/versioncheck/versioncheck_test.go | Adds unit tests for UpdateCommandForCurrentBinary. |
| cmd/entire/cli/strategy/manual_commit_push.go | Gates checkpoint pushes on pre-push policy sync / divergence / unsupported write policy. |
| cmd/entire/cli/strategy/manual_commit_hooks.go | Skips turn-checkpoint finalization when committed writes are disallowed by policy. |
| cmd/entire/cli/strategy/manual_commit_condensation.go | Skips session condensation when committed writes are disallowed by policy. |
| cmd/entire/cli/strategy/checkpoint_policy.go | Introduces strategy-layer helpers for policy gating, pre-push sync, and warn/log behavior. |
| cmd/entire/cli/strategy/checkpoint_policy_test.go | Adds strategy tests asserting policy blocks checkpoint push on unsupported write and on divergence. |
| cmd/entire/cli/explain.go | Gates --generate summary writes on committed checkpoint write policy. |
| cmd/entire/cli/explain_test.go | Refactors summary test setup; adds test that summary generation is rejected under unsupported write policy. |
| cmd/entire/cli/checkpointpolicy/warning_test.go | Adds tests for RequiresUpgrade, UnsupportedWrite, and the upgrade warning message. |
| cmd/entire/cli/checkpointpolicy/policy.go | Adds RequiresUpgrade, UnsupportedWrite, and UpgradeWarning helpers. |
| cmd/entire/cli/checkpoint_policy_write.go | Adds ensureCommittedCheckpointWritePolicy for user-driven committed write gating. |
| cmd/entire/cli/checkpoint_policy_warning.go | Adds post-success warning emission and command-exclusion logic. |
| cmd/entire/cli/checkpoint_policy_warning_test.go | Adds tests for the warning emission and exclusion logic. |
| cmd/entire/cli/attach.go | Gates attach’s committed checkpoint write path on policy support. |
| cmd/entire/cli/attach_test.go | Adds test ensuring attach rejects unsupported committed checkpoint write policy. |
Bring the policy enforcement branch up to date with its stacked base. Keep unsupported policy writes retryable during condensation and turn checkpoint finalization after the merge. Entire-Checkpoint: 4394af0269b5
Contributor
Author
|
Bugbot run |
Sync pre-push checkpoint policy from the same resolved push target used for checkpoint refs so configured checkpoint remotes are enforced consistently. Thread the checkpoint logging context through policy checks that can block condensation or finalization. Entire-Checkpoint: e77a0d40ac05
When pre-push cannot refresh checkpoint policy from the remote, still honor an already-local policy that blocks checkpoint writes. This avoids pushing checkpoint metadata with an unsupported writer just because the remote policy check failed. Entire-Checkpoint: 98531e973f39
…li into checkpoint-policy-enforcement
Contributor
Author
|
Bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit c6529b2. Configure here.
Clear pending turn checkpoint IDs when checkpoint finalization is blocked by local checkpoint policy. This matches the other best-effort finalization failures and allows ended sessions to release their shadow branches. Entire-Checkpoint: eff17371d4cd
…2.entire.io/gh/entireio/cli into checkpoint-policy-enforcement
computermode
approved these changes
Jun 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
https://entire.io/gh/entireio/cli/trails/658
Why
This is the third PR in the checkpoint-policy stack. After #1507 adds per-checkpoint format compatibility and #1508 adds the hidden policy command/storage, this PR makes the recorded repo policy affect runtime behavior.
Stacked on #1508.
What changed
The CLI now reads the local checkpoint policy before committed checkpoint writes. User-driven write paths fail when the policy requires a checkpoint format this CLI cannot write, while hook-triggered writes skip checkpoint data without failing ordinary git operations.
Pre-push refreshes the policy from the checkpoint remote before deciding whether to push
entire/checkpoints/v1, and successful user-driven commands warn when the local policy indicates the CLI should be upgraded.Usage examples
A repository can record its policy with the hidden command from the previous PR:
If that policy later requires a newer checkpoint writer, commands that create committed checkpoint data fail with an upgrade instruction instead of writing data this CLI cannot encode:
Hook-triggered checkpoint writes stay non-fatal. When run from an interactive terminal they print the same upgrade warning; otherwise they log the skipped write and let the git operation continue.
Decisions made during development
Post-commit and agent lifecycle hooks only read the local policy ref so offline git workflows keep working.
Pre-push is the refresh point because it is already an online operation. It checks the remote policy ref, fetches only when needed, and evaluates the refreshed local policy before pushing checkpoint metadata.
Successful user-driven commands warn after command execution, excluding infrastructure commands such as hooks and analytics, so users see upgrade guidance without changing unrelated command behavior.
Policy commit signature verification is intentionally not part of this PR. Policy commits are written through the existing checkpoint commit signing path, but verifying signatures for trust is a separate design problem.
Technical tradeoffs
Hook paths prefer availability over strict enforcement: if policy reading or refresh fails, most hooks log or warn and continue rather than breaking commits made by editors, agents, or offline workflows.
Pre-push treats a diverged policy ref differently from a transient refresh failure. Divergence skips the checkpoint push because the local policy state cannot be reconciled safely, while refresh failures allow the user push to continue.
The warning is based on the local policy for most commands. That keeps command startup cheap and offline-friendly, but it means users may not see remote policy changes until the local ref is refreshed by
entire policy checkpointor pre-push.Reviewer notes
This PR assumes the policy command and storage from #1508. It does not reopen or update the closed predecessor PR #1496.
Note
Medium Risk
Changes checkpoint write/push behavior across hooks and pre-push; mistakes could skip metadata silently or block legitimate writes, but failures are mostly non-fatal for git and covered by extensive tests.
Overview
Repo checkpoint policy now drives runtime behavior: the CLI reads the local policy ref and decides whether it can read/write checkpoint formats for that repository.
User-driven writes (
attach,explain --generate-summary, and similar) callensureCommittedCheckpointWritePolicyand fail with an upgrade command whencheckpoint_versionrequires a writer this binary does not support—no metadata branch advance on reject.Hook paths use
checkCommittedCheckpointWritePolicy: unsupported write policy skips checkpoint persistence (condense, turn finalize, etc.) without failing git; interactive TTY gets the upgrade warning, otherwise a log line. Policy read failures on hooks are treated as allow-write.Pre-push runs
syncCheckpointPolicyForPrePush(remote sync via push target) before pushingentire/checkpoints/v1; it skips the checkpoint push when policy is diverged, write-unsupported, or sync fails with an unsupported local policy.After successful commands, main prints a post-run upgrade warning when local policy needs a newer CLI (
RequiresUpgrade/UnsupportedWrite), excludinghooks, analytics, and install helpers.checkpointpolicyaddsRequiresUpgrade,UnsupportedWrite, andUpgradeWarning; docs describe offline hooks vs online pre-push sync.Reviewed by Cursor Bugbot for commit c6529b2. Configure here.